Skip to content

feat: support SEAM_WEBHOOK_SECRET in webhook helper - #624

Merged
razor-x merged 1 commit into
mainfrom
fm/webhook-env-ruby
Nov 18, 2026
Merged

razor-x merged 1 commit into
mainfrom
fm/webhook-env-ruby

Conversation

@razor-x

@razor-x razor-x commented Nov 18, 2026

Copy link
Copy Markdown
Member

Intent

Add SEAM_WEBHOOK_SECRET support to this maintained Seam SDK webhook helper and open a PR. This should be a small change: omitted constructor secret reads SEAM_WEBHOOK_SECRET; an explicitly supplied secret takes precedence. Preserve existing webhook verification semantics and idiomatic constructor usage. Include focused tests and examples. This is one of five parallel SDK PRs. No merge requested.

What Changed

  • Default Seam::Webhook.new to SEAM_WEBHOOK_SECRET at construction, while preserving explicit-secret precedence.
  • Reject non-string and empty secrets with actionable constructor errors.
  • Add focused secret-configuration specs and document environment-based usage and validation.

Risk Assessment

✅ Low: The change is bounded to constructor-time secret selection, preserves the verification path, and includes focused behavioral tests and examples.

Testing

All four real-SDK scenarios passed with independently signed synthetic events, and all focused webhook specs passed. Bundler's missing development dependency was bypassed without installing anything. Captured SDK transcript and reproducible driver; cleaned temporary state. No UI surface or background processes.

  • Live validation: ✅ go - 4 of 4 scenarios driven live against the product
Scenario Result Live Evidence
Local Ruby SDK uses synthetic environment secrets at construction and preserves existing helpers after rotation ✅ pass live sdk_live.log: environment default and construction-time rotation
Local Ruby SDK accepts an explicit positional secret and rejects events signed with the competing environment key ✅ pass live sdk_live.log: explicit positional secret overrides environment
Local Ruby SDK rejects missing defaults, explicit nil/non-string inputs, and empty keys without falling back ✅ pass live sdk_live.log: missing, invalid, and decoded-empty secrets fail closed
Local environment-configured SDK parses a signed typed event and rejects tampering, stale signatures, missing headers, and signed malformed JSON ✅ pass live sdk_live.log: environment helper preserves verification safeguards and parsing
Evidence: Local SDK execution transcript

Real SDK accepted independently signed events and rejected wrong keys, tampering, expired timestamps, missing headers, and invalid secrets.

SCENARIO environment default and construction-time rotation
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
REJECT new helper rejects previous environment key: Svix::WebhookVerificationError: No matching signature found
SCENARIO explicit positional secret overrides environment
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
REJECT environment key cannot authenticate explicit helper: Svix::WebhookVerificationError: No matching signature found
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
SCENARIO missing, invalid, and decoded-empty secrets fail closed
REJECT missing default: TypeError: Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET
REJECT explicit nil: TypeError: Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET
REJECT explicit false: TypeError: Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET
REJECT explicit 123: TypeError: Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET
REJECT explicit {}: TypeError: Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET
REJECT explicit "": Svix::EmptyWebhookSecretError: Pass a webhook secret or set SEAM_WEBHOOK_SECRET to a non-empty value
REJECT environment "": Svix::EmptyWebhookSecretError: Pass a webhook secret or set SEAM_WEBHOOK_SECRET to a non-empty value
REJECT explicit "whsec_": Svix::EmptyWebhookSecretError: Webhook secret must not be blank
REJECT environment "whsec_": Svix::EmptyWebhookSecretError: Webhook secret must not be blank
REJECT explicit " ": Svix::EmptyWebhookSecretError: Webhook secret must not be blank
REJECT environment " ": Svix::EmptyWebhookSecretError: Webhook secret must not be blank
SCENARIO environment helper preserves verification safeguards and parsing
ACCEPT event_id=event-local device_id=device-local class=Seam::Resources::SeamEvent::DeviceConnected
REJECT tampered body: Svix::WebhookVerificationError: No matching signature found
REJECT expired timestamp: Svix::WebhookVerificationError: Message timestamp too old
REJECT missing Svix-Id: Svix::WebhookVerificationError: Missing required headers
REJECT missing Svix-Timestamp: Svix::WebhookVerificationError: Missing required headers
REJECT missing Svix-Signature: Svix::WebhookVerificationError: Missing required headers
REJECT signed malformed JSON: Seam::InvalidWebhookPayloadError: The verified webhook payload is not valid JSON: expected object key, got EOF at line 1 column 2
All four local SDK scenarios completed successfully.
Evidence: Reproducible independent HMAC SDK driver
require 'seam'
require 'openssl'
require 'base64'
require 'json'
# Independent oracle: Svix wire contract v1 = base64(HMAC-SHA256(key, id.timestamp.body)).
# Exercise the actual Seam SDK, without RSpec, WebMock, or replacing any product component.
A = 'synthetic-environment-key'
B = 'synthetic-explicit-key'
def secret(key) = 'whsec_' + Base64.strict_encode64(key)
def headers(body, key, timestamp = Time.now.to_i)
  id = 'msg-local-validation'
  signature = Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', key, "#{id}.#{timestamp}.#{body}"))
  {'Svix-Id'=>id, 'Svix-Timestamp'=>timestamp.to_s, 'Svix-Signature'=>"v1,#{signature}"}
end
def verify(helper, body, key)
  event = helper.verify(body, headers(body, key))
  raise 'Incorrect event' unless event.event_id == 'event-local' && event.device_id == 'device-local'
  puts "ACCEPT event_id=#{event.event_id} device_id=#{event.device_id} class=#{event.class}"
end
def reject(label, type)
  begin
    yield
  rescue type => e
    puts "REJECT #{label}: #{e.class}: #{e.message}"
    return
  end
  raise "Unexpected acceptance: #{label}"
end
body = {event_id:'event-local', event_type:'device.connected', device_id:'device-local'}.to_json
puts 'SCENARIO environment default and construction-time rotation'
ENV['SEAM_WEBHOOK_SECRET'] = secret(A)
first = Seam::Webhook.new
verify(first, body, A)
ENV['SEAM_WEBHOOK_SECRET'] = secret(B)
second = Seam::Webhook.new
verify(first, body, A)
verify(second, body, B)
reject('new helper rejects previous environment key', Seam::WebhookVerificationError) { second.verify(body, headers(body, A)) }
puts 'SCENARIO explicit positional secret overrides environment'
explicit = Seam::Webhook.new(secret(A))
verify(explicit, body, A)
reject('environment key cannot authenticate explicit helper', Seam::WebhookVerificationError) { explicit.verify(body, headers(body, B)) }
ENV.delete('SEAM_WEBHOOK_SECRET')
verify(Seam::Webhook.new(secret(A)), body, A)
puts 'SCENARIO missing, invalid, and decoded-empty secrets fail closed'
reject('missing default', TypeError) { Seam::Webhook.new }
ENV['SEAM_WEBHOOK_SECRET'] = secret(A)
[nil, false, 123, {}].each { |value| reject("explicit #{value.inspect}", TypeError) { Seam::Webhook.new(value) } }
['', 'whsec_', ' '].each do |value|
  ENV['SEAM_WEBHOOK_SECRET'] = secret(A)
  reject("explicit #{value.inspect}", Svix::EmptyWebhookSecretError) { Seam::Webhook.new(value) }
  ENV['SEAM_WEBHOOK_SECRET'] = value
  reject("environment #{value.inspect}", Svix::EmptyWebhookSecretError) { Seam::Webhook.new }
end
puts 'SCENARIO environment helper preserves verification safeguards and parsing'
ENV['SEAM_WEBHOOK_SECRET'] = secret(A)
helper = Seam::Webhook.new
verify(helper, body, A)
reject('tampered body', Seam::WebhookVerificationError) { helper.verify(body.sub('device-local','tampered'), headers(body,A)) }
reject('expired timestamp', Seam::WebhookVerificationError) { helper.verify(body, headers(body,A,Time.now.to_i-600)) }
%w[Svix-Id Svix-Timestamp Svix-Signature].each do |name|
  reject("missing #{name}", Seam::WebhookVerificationError) { helper.verify(body,headers(body,A).reject { |k,v| k == name }) }
end
bad = '{'
reject('signed malformed JSON', Seam::InvalidWebhookPayloadError) { helper.verify(bad,headers(bad,A)) }
puts 'All four local SDK scenarios completed successfully.'

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 4 of 4 scenarios driven live against the product
Scenario Result Live Evidence
Local Ruby SDK uses synthetic environment secrets at construction and preserves existing helpers after rotation ✅ pass live sdk_live.log: environment default and construction-time rotation
Local Ruby SDK accepts an explicit positional secret and rejects events signed with the competing environment key ✅ pass live sdk_live.log: explicit positional secret overrides environment
Local Ruby SDK rejects missing defaults, explicit nil/non-string inputs, and empty keys without falling back ✅ pass live sdk_live.log: missing, invalid, and decoded-empty secrets fail closed
Local environment-configured SDK parses a signed typed event and rejects tampering, stale signatures, missing headers, and signed malformed JSON ✅ pass live sdk_live.log: environment helper preserves verification safeguards and parsing
  • ruby --version; bundle check — Ruby 4.0.0; Bundler reported missing development dependency addressable 2.9.1.
  • MISE_STATE_DIR="$PWD/.test-state" ruby -Ilib -rseam -e 'puts "SDK loaded"'
  • MISE_STATE_DIR="$PWD/.test-state" ruby -Ilib ~/seam/.firstmate/flagship/no-mistakes/evidence/01M7R3S5926GWV8JZR44A8VRHB/sdk_live.rb — exit 0.
  • MISE_STATE_DIR="$PWD/.test-state" ruby -Ilib -S rspec --options /dev/null --require seam spec/webhook_spec.rb --format documentation — 35 examples, zero failures; bypassed unrelated shared WebMock/coverage setup.
  • Read retained execution logs and actual exit statuses; removed disposable mise state; verified clean worktree.
✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → no changes applied ✅
  • ⚠️ Gemfile.lock:1 - Ruby lint verification is blocked: bundle exec standardrb lib/seam/webhook.rb spec/webhook_spec.rb cannot load the locked dependency addressable-2.9.1 because it is not installed. README Prettier and git diff whitespace checks passed; documentation already reflects the implementation. No tests or dependency installations were run.

🔧 No changes applied.
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.

@razor-x
razor-x merged commit d8a93d8 into main Nov 18, 2026
17 checks passed
@razor-x
razor-x deleted the fm/webhook-env-ruby branch November 18, 2026 20:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant